Movie Controller Actions2

This section discusses actions, which are integer constants (defined by the mcAction data type) used by movie controller components. Applications that use movie controller components can invoke these actions by calling the MCDoAction function, which is described on MCDoAction . If your application includes an action filter function, that function may receive any of these actions (see the discussion of the MCSetActionFilterWithRefCon function on MCSetActionFilterWithRefCon for more information about action filter functions).

Your action filter function should refer any actions that you do not want to handle back to the calling movie controller component. Your function refers actions back to the movie controller component by returning a value of false . If your function returns a value of true , the movie controller component performs no further processing for the action.

If you use any Movie Toolbox functions that modify the movie in your action filter function, be sure to call the MCMovieChanged function (described on MCMovieChanged ).

The action descriptions that follow are divided into those used by your application and those received by your action filter.

Actions for Use by Applications

mcActionIdle: Your application can use this action to grant event-processing time to a movie controller.; There are no parameters for this action.
mcActionDraw: Your application can use this action to send an update event to a movie controller.; The parameter for this action is a pointer to a window.
mcActionActivate: Your application can use this action to activate a movie controller.; There are no parameters for this action.
mcActionDeactivate: Your application can use this action to deactivate a movie controller.; There are no parameters for this action.
mcActionMouseDown: Your application can use this action to pass a mouse-down event to a movie controller.; The parameter data must contain a pointer to an event structure--the message field in the event structure must specify the window in which the user clicked.
mcActionKey: Your application can use this action to pass a key-down or auto-key event to a movie controller.; The parameter data must contain a pointer to an event structure that describes the key event.; Your action filter function receives this action when the movie controller has received a key-down or auto-key event.
mcActionPlay: Your application can use this action to start or stop playing a movie .; The parameter data must contain a fixed value that indicates the rate of play. Values greater than 0 correspond to forward rates; values less than 0 play the movie backward. A value of 0 stops the movie.
mcActionGotoTime: Your application can use this action to move to a specific time in a movie.; The parameter data must contain a pointer to a time structure that specifies the target position in the movie.
mcActionSetVolume: Your application can use this action to set a movie's volume.; The parameter data must contain a pointer to a 16-bit, fixed-point number that indicates the relative volume of the movie. Volume values range from -1.0 to 1.0. Negative values play no sound but preserve the absolute value of the volume setting.
mcActionGetVolume: Your application can use this action to determine a movie's volume.; The parameter data must contain a pointer to a 16-bit, fixed-point number that indicates the relative volume of the movie. Volume values range from -1.0 to 1.0. Negative values play no sound but preserve the absolute value of the volume setting.
mcActionStep: Your application can use this action to play a movie while skipping a specified number of frames at a time.; The parameter data must contain a long integer value that specifies the number of steps (that is, the frames and the play direction). Positive values step the movie forward the specified number of frames; negative values step the movie backward. A value of 0 steps the movie forward one frame.
mcActionSetLooping: Your application can use this action to enable or disable looping for a movie.; The parameter data must contain a Boolean value--a value of true indicates that looping is to be enabled.
mcActionGetLooping: Your application can use this action to determine whether a movie is looping.; The parameter data must contain a pointer to a Boolean value. The movie controller sets this value to true if looping is enabled for the movie that is assigned to this controller. Otherwise, it sets the value to false .
mcActionSetLoopIsPalindrome: Your application can use this action to enable palindrome looping. Palindrome looping causes a movie to play alternately forward and backward. Looping must also be enabled for palindrome looping to take effect.; The parameter data must contain a Boolean value--a value of true indicates that palindrome looping is to be enabled.
mcActionGetLoopIsPalindrome: Your application can use this action to determine whether palindrome looping is enabled for a movie. Looping must also be enabled for palindrome looping to take effect.; The parameter data must contain a pointer to a Boolean value. The movie controller sets this value to true if palindrome looping is enabled for the movie that is assigned to this controller. Otherwise, it sets the value to false .
mcActionSetGrowBoxBounds: Your application can use this action to set the limits for resizing a movie.; The parameter data consists of a rect structure.
mcActionSetSelectionBegin: Your application can use this action to set the start time of a movie's current selection. After using this action, you must use the mcActionSetSelectionDuration action to set the duration of the selection.; The parameter data must contain a pointer to a time structure specifying the starting time of the movie's current selection.
mcActionSetSelectionDuration: Your application can use this action to set the duration of a movie's current selection. You can only use this action immediately after the mcActionSetSelectionBegin action.; The parameter data must contain a pointer to a time structure specifying the ending time of the movie's current selection.; Your action filter function receives this action when the movie controller has received a request to set the movie's current selection duration.
mcActionSetKeysEnabled: Your application can use this action to enable or disable keystrokes for a movie.; The parameter data must contain a Boolean value--a value of true indicates that keystrokes are to be enabled. By default, this value is set to false .
mcActionGetKeysEnabled: Your application can use this action to determine whether keystrokes are enabled for a movie controller.; The parameter data must contain a pointer to a Boolean value. The movie controller sets this value to true if keystrokes are enabled for the movie that is assigned to this controller. Otherwise, it sets the value to false .
mcActionSetPlaySelection: Your application can use this action to constrain playing to the current selection.; The parameter data must contain a Boolean value--a value of true indicates that playing within the current selection is to be enabled.
mcActionGetPlaySelection: Your application can use this action to determine whether a movie has been constrained to playing within its selection.; The parameter data must contain a pointer to a Boolean value. The movie controller sets this value to true if playing is constrained to the current selection. Otherwise, it sets the value to false .
mcActionSetUseBadge: Your application can use this action to enable or disable a movie's playback badge. If a controller's badge is enabled, then the badge is displayed whenever the controller is not visible. When the controller is visible, the badge is not displayed. If the badge is disabled, the badge is never displayed.; The parameter data must contain a Boolean value--a value of true indicates that the playback badge is to be enabled.
mcActionGetUseBadge: Your application can use this action to determine whether a controller is using a badge. If a controller's badge is enabled, then the badge is displayed whenever the controller is not visible. When the controller is visible, the badge is not displayed. If the badge is disabled, the badge is never displayed.; The parameter data must contain a pointer to a Boolean value. The movie controller sets this value to true if the controller is using a badge. Otherwise, it sets the value to false .
mcActionSetFlags: Your application can use this action to set a movie's control flags.; The parameter data must contain a long integer that contains the new control flag values. The following flags are defined:
mcActionGetFlags: Your application can use this action to retrieve a movie's control flags.; The parameter data must contain a pointer to a long integer. The movie controller places the movie's control flags into that long integer. The following movie control flags are defined:
mcActionSetPlayEveryFrame: Your application can use this action to instruct the movie controller to play every frame in a movie. In this case, the movie controller may play the movie at a slower rate than you specify with the mcActionPlay action. However, the controller does not play the movie faster than the movie rate. In addition, the controller does not play the movie's sound tracks.; The parameter data must contain a Boolean value--a value of true instructs the controller to play every frame in the movie, even if that means playing the movie at a slower rate than you previously specified.
mcActionGetPlayEveryFrame: Your application can use this action to determine whether the movie controller has been instructed to play every frame in a movie. You tell the controller to play every frame by using the mcActionSetPlayEveryFrame action, which is described earlier in this section.; The parameter data must contain a pointer to a Boolean value--the movie controller sets this value to true if the controller has been instructed to play every frame in the movie, even if that means playing the movie at a slower rate than you previously specified. Otherwise, the controller sets the value to false .
mcActionSetGrowBoundsBox: The parameter data must contain a pointer to a rectangle--set the rectangle to the boundary coordinates for the movie. If you want to prevent the movie from being resized, supply an empty rectangle (note that enabling or disabling the size box may change the appearance of some movie controllers). By default, movie controllers do not have size boxes. You must use this action to establish a size box for a movie controller.; If the movie controller's boundary rectangle intersects the lower-right corner of your window, your window cannot have a size box.
mcActionGetPlayRate: Your application can use this action to determine a movie's playback rate. You set the playback rate when you start a movie playing by using the mcActionPlay action.; The parameter data must contain a pointer to a fixed value. The movie controller returns the movie's playback rate in that fixed value. Values greater than 0 correspond to forward rates; values less than 0 play the movie backward. A value of 0 indicates that the movie is stopped.
mcActionBadgeClick: Indicates that the badge was clicked. The parameter is a pointer to a Boolean value. On entry, the Boolean is set to true . Set the Boolean to false if you want the controller to ignore the click in the badge.
mcActionMovieClick: Indicates that the movie was clicked. The parameter is a pointer to an event structure containing the mouse-down event. If you want the controller to ignore the mouse-down event, change the what field of the event structure to a null event.
mcActionSuspend: Indicates that a suspend event has been received. There is no parameter.
mcActionResume: Indicates that a resume event has been received. There is no parameter.

Actions for Use by Action-Filter Functions

mcActionIdle: Your action filter function receives this action when the application has granted null event-processing time to the movie controller.; There are no parameters for this action.
mcActionDraw: Your filter function receives this action when the controller has received an update event.; The parameter for this action is a pointer to a window.
mcActionActivate: Your filter function receives this action when the controller has received an activate or resume event.; There are no parameters for this action.
mcActionDeactivate: Your filter function receives this action when the controller has received a deactivate or suspend event.; There are no parameters for this action.
mcActionMouseDown: Your action filter function receives this action when the movie controller has received a mouse-down event.; The parameter data must contain a pointer to an event structure--the message field in the event structure must specify the window in which the user clicked.
mcActionKey: Your action filter function receives this action when the movie controller has received a key-down or auto-key event.; The parameter data must contain a pointer to an event structure that describes the key event.
mcActionPlay: Your action filter receives this action when the movie controller has received a request to start or stop playing a movie.; The parameter data must contain a fixed value that indicates the rate of play. Values greater than 0 correspond to forward rates; values less than 0 play the movie backward. A value of 0 stops the movie.
mcActionGotoTime: Your action filter function receives this action when the movie controller has received a request to go to a specified time in the movie.; The parameter data must contain a pointer to a time structure that specifies the target position in the movie.
mcActionSetVolume: Your action filter function receives this action when the movie controller has received a request to set the movie's volume.; The parameter data must contain a pointer to a 16-bit, fixed-point number that indicates the relative volume of the movie. Volume values range from -1.0 to 1.0. Negative values play no sound but preserve the absolute value of the volume setting.
mcActionGetVolume: Your action filter function receives this action when the movie controller has received a request to retrieve the movie's volume.; The parameter data must contain a pointer to a 16-bit, fixed-point number that indicates the relative volume of the movie. Volume values range from -1.0 to 1.0. Negative values play no sound but preserve the absolute value of the volume setting.
mcActionStep: Your action filter function receives this action when the movie controller has received a request to play a movie while advancing a specified number of frames at a time.; The parameter data must contain a long integer value that specifies the number of steps (that is, the frames and the play direction). Positive values step the movie forward the specified number of frames; negative values step the movie backward. A value of 0 steps the movie forward one frame.
mcActionSetLooping: Your action filter function receives this action when the movie controller has received a request to turn looping on or off.; The parameter data must contain a Boolean value--a value of true indicates that looping is to be enabled.
mcActionGetLooping: Your action filter function receives this action when the controller has received a request to indicate whether looping is enabled for its movie.; The parameter data must contain a pointer to a Boolean value. The movie controller sets this value to true if looping is enabled for the movie that is assigned to this controller. Otherwise, it sets the value to false .
mcActionSetLoopIsPalindrome: Your action filter function receives this action when the movie controller has received a request to turn palindrome looping on or off. Palindrome looping causes a movie to play alternately forward and backward. Looping must also be enabled for palindrome looping to take effect.; The parameter data must contain a Boolean value--a value of true indicates that palindrome looping is to be enabled.
mcActionGetLoopIsPalindrome: Your action filter function receives this action when the controller has received a request to indicate whether palindrome looping is enabled for its movie.; The parameter data must contain a pointer to a Boolean value. The movie controller sets this value to true if palindrome looping is enabled for the movie that is assigned to this controller. Otherwise, it sets the value to false .
mcActionControllerSizeChanged: Your filter function receives this action when the user has resized the movie controller--the controller component issues this action before it updates the screen, allowing your application to change the controller's location or appearance before the user sees the resized controller.; There are no parameters for this action.

Note

Your application should never use this action.

mcActionSetSelectionBegin: Your action filter function receives this action when the movie controller has received a request to set the movie's current selection start time.; The parameter data must contain a pointer to a time structure specifying the starting time of the movie's current selection.
mcActionSetSelectionDuration: Your action filter function receives this action when the movie controller has received a request to set the movie's current selection duration.; The parameter data must contain a pointer to a time structure specifying the ending time of the movie's current selection.
mcActionSetKeysEnabled: Your action filter function receives this action when the movie controller has received a request to enable or disable keystrokes.; The parameter data must contain a Boolean value--a value of true indicates that keystrokes are to be enabled. By default, this value is set to false .
mcActionGetKeysEnabled: Your filter function receives this action when the controller has received a request to indicate whether keystrokes are enabled for its movie.; The parameter data must contain a pointer to a Boolean value. The movie controller sets this value to true if keystrokes are enabled for the movie that is assigned to this controller. Otherwise, it sets the value to false .
mcActionSetPlaySelection: Your action filter function receives this action when the movie controller has received a request to constrain playing to the current selection.; The parameter data must contain a Boolean value--a value of true indicates that playing within the current selection is to be enabled.
mcActionGetPlaySelection: Your action filter function receives this action when the movie controller has received a request to indicate whether playing is constrained to the current selection.; The parameter data must contain a pointer to a Boolean value. The movie controller sets this value to true if playing is constrained to the current selection. Otherwise, it sets the value to false .
mcActionSetUseBadge: Your action filter function receives this action when the movie controller has received a request to turn the playback badge on or off.; The parameter data must contain a Boolean value--a value of true indicates that the playback badge is to be enabled.
mcActionGetUseBadge: Your action filter function receives this action when the controller has received a request to indicate whether it is using a badge during playback.; The parameter data must contain a pointer to a Boolean value. The movie controller sets this value to true if the controller is using a badge. Otherwise, it sets the value to false .
mcActionSetFlags: Your action filter function receives this action when the movie controller has received a request to set the movie's control flags .; The parameter data must contain a long integer that contains the new control flag values. The following flags are defined:
mcActionGetFlags: Your action filter function receives this action when the movie controller has received a request to retrieve the movie's control flags.; The parameter data must contain a pointer to a long integer. The movie controller places the movie's control flags into that long integer. The following movie control flags are defined:
mcActionSetPlayEveryFrame: Your action filter function receives this action when the movie controller has received a request to play every frame in a movie.; The parameter data must contain a Boolean value--a value of true instructs the controller to play every frame in the movie, even if that means playing the movie at a slower rate than you previously specified.
mcActionGetPlayEveryFrame: Your action filter function receives this action when the movie controller has received a request to indicate whether it has been instructed to play every frame in a movie.; The parameter data must contain a pointer to a Boolean value--the movie controller sets this value to true if the controller has been instructed to play every frame in the movie, even if that means playing the movie at a slower rate than you previously specified. Otherwise, the controller sets the value to false .
mcActionSetGrowBoundsBox: Your action filter function receives this action when the movie controller has received a request to set the limits for resizing the movie.; The parameter data contains a pointer to a rectangle--the rectangle defines the boundary coordinates for the movie. If the rectangle is empty, the application wants to disable the size box. You may change the appearance of your controller in response to such a request.
mcActionShowBalloon: Your action filter function receives this action when the controller wants to display Balloon Help. Your filter function instructs the controller whether to display the Balloon Help. This action allows you to override the movie controller's default Balloon Help behavior.; The parameter data contains a pointer to a Boolean value. Set the value to true to display the appropriate Balloon Help. Otherwise, set the value to false .

Note

Your application should never use this action.